type-graphql

What is type-graphql?

type-graphql is a library that allows you to create GraphQL APIs using TypeScript. It leverages TypeScript's type system to define the schema and resolvers, making it easier to maintain and understand. The library provides decorators and other utilities to simplify the creation of GraphQL schemas and resolvers.

What are type-graphql's main functionalities?

Schema Definition

This feature allows you to define your GraphQL schema using TypeScript classes and decorators. The example demonstrates how to create a simple object type and a resolver with a query.

const { buildSchema } = require('type-graphql');
const { Resolver, Query, ObjectType, Field } = require('type-graphql');

@ObjectType()
class SampleObject {
  @Field()
  id: number;

  @Field()
  name: string;
}

@Resolver()
class SampleResolver {
  @Query(() => SampleObject)
  sampleQuery() {
    return { id: 1, name: 'Sample' };
  }
}

async function main() {
  const schema = await buildSchema({
    resolvers: [SampleResolver],
  });
  // Use the schema in your GraphQL server setup
}
main();

Resolvers

Resolvers are used to handle the logic for fetching and manipulating data. This example shows how to create a resolver with a query to get users and a mutation to add a user.

const { Resolver, Query, Arg, Mutation } = require('type-graphql');

@Resolver()
class UserResolver {
  private users = [];

  @Query(() => [String])
  getUsers() {
    return this.users;
  }

  @Mutation(() => String)
  addUser(@Arg('name') name: string) {
    this.users.push(name);
    return name;
  }
}

async function main() {
  const schema = await buildSchema({
    resolvers: [UserResolver],
  });
  // Use the schema in your GraphQL server setup
}
main();

Custom Scalars

Custom scalars allow you to define custom data types in your GraphQL schema. This example demonstrates how to create a custom scalar for handling Date objects.

const { Scalar, CustomScalar } = require('type-graphql');
const { GraphQLScalarType, Kind } = require('graphql');

@Scalar('Date')
class DateScalar implements CustomScalar<string, Date> {
  description = 'Date custom scalar type';

  parseValue(value: string): Date {
    return new Date(value); // value from the client input variables
  }

  serialize(value: Date): string {
    return value.toISOString(); // value sent to the client
  }

  parseLiteral(ast: any): Date {
    if (ast.kind === Kind.STRING) {
      return new Date(ast.value); // value from the client query
    }
    return null;
  }
}

async function main() {
  const schema = await buildSchema({
    resolvers: [],
    scalarsMap: [{ type: Date, scalar: DateScalar }],
  });
  // Use the schema in your GraphQL server setup
}
main();

Other packages similar to type-graphql

apollo-server

Apollo Server is a community-driven, open-source GraphQL server that works with any GraphQL schema built with GraphQL.js. It provides a more flexible and powerful way to build GraphQL APIs but does not integrate TypeScript as tightly as type-graphql.

graphql-tools

graphql-tools is a set of utilities from Apollo that helps you create and manipulate GraphQL schemas in a more flexible way. It allows you to build schemas using a schema-first approach, but it does not provide the same level of TypeScript integration as type-graphql.

nexus

Nexus is a code-first GraphQL schema construction library for TypeScript & JavaScript. It provides a similar experience to type-graphql but with a different API and philosophy. Nexus focuses on a more functional approach compared to the decorator-based approach of type-graphql.

README

TypeGraphQL

Create GraphQL schema and resolvers with TypeScript, using classes and decorators!

https://typegraphql.com/

Introduction

TypeGraphQL makes developing GraphQL APIs an enjoyable process, i.e. by defining the schema using only classes and a bit of decorator magic.

So, to create types like object type or input type, we use a kind of DTO classes. For example, to declare Recipe type we simply create a class and annotate it with decorators:

@ObjectType()
class Recipe {
  @Field(type => ID)
  id: string;

  @Field()
  title: string;

  @Field(type => [Rate])
  ratings: Rate[];

  @Field({ nullable: true })
  averageRating?: number;
}

And we get the corresponding part of the schema in SDL:

type Recipe {
  id: ID!
  title: String!
  ratings: [Rate!]!
  averageRating: Float
}

Then we can create queries, mutations and field resolvers. For this purpose we use controller-like classes that are called "resolvers" by convention. We can also use awesome features like dependency injection and auth guards:

@Resolver(Recipe)
class RecipeResolver {
  // dependency injection
  constructor(private recipeService: RecipeService) {}

  @Query(returns => [Recipe])
  recipes() {
    return this.recipeService.findAll();
  }

  @Mutation()
  @Authorized(Roles.Admin) // auth guard
  removeRecipe(@Arg("id") id: string): boolean {
    return this.recipeService.removeById(id);
  }

  @FieldResolver()
  averageRating(@Root() recipe: Recipe) {
    return recipe.ratings.reduce((a, b) => a + b, 0) / recipe.ratings.length;
  }
}

And in this simple way we get this part of the schema in SDL:

type Query {
  recipes: [Recipe!]!
}

type Mutation {
  removeRecipe(id: String!): Boolean!
}

Motivation

We all know that GraphQL is great and solves many problems we have with REST APIs, like overfetching and underfetching. But developing a GraphQL API in Node.js with TypeScript is sometimes a bit of a pain. Why? Let's take a look at the steps we usually have to take.

First, we create all the GraphQL types in schema.gql using SDL. Then we create our data models using ORM classes, which represent our db entities. Then we start to write resolvers for our queries, mutations and fields, but this forces us to first create TS interfaces for all arguments, inputs, and even object types.

Only then can we actually implement the resolvers using weird generic signatures and manually performing common tasks, like validation, authorization and loading dependencies:

export const getRecipesResolver: GraphQLFieldResolver<void, Context, GetRecipesArgs> =
  async (_, args, ctx) => {
    // common tasks repeatable for almost every resolver
    const repository = TypeORM.getRepository(Recipe);
    const auth = Container.get(AuthService);
    await joi.validate(getRecipesSchema, args);
    if (!auth.check(ctx.user)) {
      throw new NotAuthorizedError();
    }

    // our business logic, e.g.:
    return repository.find({ skip: args.offset, take: args.limit });
  };

The biggest problem is redundancy in our codebase, which makes it difficult to keep things in sync. To add a new field to our entity, we have to jump through all the files - modify an entity class, the schema, as well as the interface. The same goes for inputs or arguments. It's easy to forget to update one piece or make a mistake with a single type. Also, what if we've made a typo in field name? The rename feature (F2) won't work correctly.

Tools like GraphQL Code Generator or graphqlgen only solve the first part - they generate the corresponding interfaces (and resolvers skeletons) for our GraphQL schema but they don't fix the schema <--> models redundancy and developer experience (F2 rename won't work, you have to remember about the codegen watch task in background, etc.), as well as common tasks like validation, authorization, etc.

TypeGraphQL comes to address these issues, based on experience from a few years of developing GraphQL APIs in TypeScript. The main idea is to have only one source of truth by defining the schema using classes and some help from decorators. Additional features like dependency injection, validation and auth guards help with common tasks that normally we would have to handle ourselves.

Documentation

The documentation, installation guide, detailed description of the API and all of its features is available on the website.

Getting started

A full getting started guide with a simple walkthrough (tutorial) can be found at getting started docs.

Video tutorial

If you prefer video tutorials, you can watch Ben Awad's TypeGraphQL video series on YouTube.

Examples

You can also check the examples folder in this repository for more examples of usage: simple fields resolvers, DI Container support, TypeORM integration, automatic validation, etc.

The Tests folder might also give you some tips how to get various things done.

The future

The currently released version is a stable 1.0.0 release. It is well tested (95% coverage, 428 test cases) and has most of the planned features already implemented. Plenty of companies and independent developers are using it in production with success.

However, there are also plans for a lot more features like better TypeORM, Prisma and dataloader integration, custom decorators and metadata annotations support - the full list of ideas is available on the GitHub repo. You can also keep track of development's progress on project board.

If you have any interesting feature requests, feel free to open an issue on GitHub so we can discuss that!

Support

TypeGraphQL is an MIT-licensed open source project. This framework is a result of the tremendous amount of work - sleepless nights, busy evenings and weekends.

It doesn't have a large company that sits behind - its ongoing development is possible only thanks to the support by the community.

Gold Sponsors 🏆

BlueReceipt	ECAD Labs

Please ask your company to support this open source project by becoming a gold sponsor and getting a premium technical support from our core contributors.

Silver Sponsors 🥈

Gorrion Software House	Mr Yum

Bronze Sponsors 🥉

Live Graphic Systems	LifeX Aps	SwissMentor

Members 💪 and Backers ☕

Want to help?

Want to file a bug, contribute some code, or improve documentation? Great! Please read our guidelines for contributing and then check out one of our help wanted issues.

Changelog

v1.1.1

Fixes

• fix crashing when of union's or interface type's resolveType function returns undefined or null (#731)
• fix crashing when no reflected type available for fields with params decorators (#724)
• fix not registering object types implementing interface type when interface type is used as object type field type (#736)
• properly transform nested array of input type classes (#737)